////////////////////////////////////////////////////////////////////////
//                                                                    //
// KconfigSize : Linux kernel size and memory usage measurement tool  //
// Connection and setting between host and target machine             //
//                                                                    //
////////////////////////////////////////////////////////////////////////


Introduction
============================================================
This document describes necessary items in memory measurement process. 
- connection between host and target machine
- target machine setting
- host machine setting
- stream converter specification
- reset helper specification


connection between host and target machine
============================================================
The following requirements must be satisfied.
- kernel image can be downloaded from host machine using tftp, etc.
- host machine can access console output of target machine by serial
  console, etc. 
- host machine can reboot target machine using command.

Typical connection is described in the following diagram. 

~~~~~~ Fig.1 Host/Target Connection Diagram ~~~~~~

+------+           ether (for tftp)              +------+
|      |<--------------------------------------->|      |
|      |                                         |      |
|      |           serial (for console)          |      |
| host |<--------------------------------------->|target|
|      |                                         |      |
|      |                    relay box            |      |
|      | parallel (for reset) +---+  power line  |      |
|      |<-------------------->|   |<------------>|      |
+------+                      +---+              +------+
                                |
                                \/
                          (power source)

"Relay box" is a power control equipment. Relay box in Fig.1 is connected
to parallel port of host machine. It is controlled by host machine to reboot 
target machine by manipulating the power of target machine in following 
order: ON->OFF->ON. 


target machine setting
============================================================

--- (1) boot
Target machine must be able to download kernel image from host machine and
boot. Generally tftp method is used for the downloading. KconfigSize tool will
copy kernel image to a specific place in host, and then reset target machine.
For specifying where kernel image should be copied, please refer to
configure_en.txt for further details. Target machine bootloader must be set
to download kernel image from this place and then boot. 

--- (2) console
Set primary console as the device connected to host. Generally serial console 
is used. Under such circumstances, in order to set serial device as primary 
console, kernel boot parameter should be specified as:  
     console=/dev/ttyS0.

--- (3) memory measurement
As boot script(/etc/rc?.d), kconfigsize/bin/target/memfree.sh should be set 
as executable.  Generally set as following in target machine. 
(assuming default run level is 1)

# cp kconfigsize/bin/target/memfree.sh /etc/init.d 
# cd /etc/rc1.d
# ln -s ../init.d/memfree.sh S99memfree

memfree.sh requires the following commands: dmesg, expr, sed and grep.
So these commands must be installed to target machine.


host machine setting
============================================================

--- (1) supply kernel image for target machine
The host machine must be able to supply kernel image to target machine.
Generally tftp server is used in host machine. Furthermore, the permission 
of export directory must be set correctly. KconfigSize tool should have 
permission to write to that directory.

--- (2) communicate with target machine console
Set host machine to be able to read console output from target machine.
Furthermore, KconfigSize tool use program called "stream converter" to
read console output from target machine. For details of "stream converter",
please refer to "stream converter specification" later.

--- (3) reset target machine
Set host machine to be able to reset target machine.
KconfigSize tool will call program named "reset helper" to reset target 
machine. For details of "reset helper", please refer to 
"reset helper specification" later. 


stream converter specification
============================================================

--- (1) Introduction
stream converter is a program that delivers the console output of target 
machine to KconfigSize tool.

While reset target machine, KconfigSize tool will start stream converter at 
the same time and use pipe to read standard output of stream converter. 
Once memory measurement is completed, KconfigSize tool will stop stream 
converter and reset target machine. Then stream converter is restarted and 
measurement circle repeats. 

Stream converter can be specified in configuration file. 
(for further details, please refer to configure_en.txt)
In KconfigSize tree, there is a stream converter named "sstream" for 
serial console. For other method, new stream converter need to be made. 
Necessary information on how to make stream converter is described as below.
 
--- (2) demand functions
Stream converter need meet below requirements. 
- direct the console output of target machine to standard output.
- once obtain memory measurement result, KconfigSize tool sends SIGTERM to 
  stream converter. If something need to be done between memory measurement 
  and the reset of target machine, signal handler of SIGTERM can be defined. 
  Furthermore, just before the reset of target machine, KconfigSize tool 
  sends SIGKILL to the stream converter.


reset helper specification
============================================================

The reset helper is a program to reset the target machine. 
It can be specified by the configuration file. (for further details, please 
refer to configure_en.txt)

In KconfigSize tree, there is a reset helper called "treset".
(Program Kconfigsize tool directly calls is "parallel_reset.sh" which is a
wrapper script.)
Treset is a program to control the relay box through parallel port. The relay
box is connected to the power line of the target machine.
For other method, new reset helper need to be made. 

There is no special requirement for the reset helper except being able to reset 
the target machine. 
